(See also the Monitor Command Manual, online as MONCOM.BH[S,DOC], for details
on the LOGIN option CHRMAC which makes LOGIN set up your macros for you.)

There are now terminal-input macros available on all terminals.
Such macros make it possible to type a short string of characters
(possibly one character) to get the effect of typing many
characters.

    Note: Many programs provide for defining macros within the program.
    The macros described here have nothing to do with such program-defined
    macros.  The definitions of macros described here are maintained by
    the system and are available to the terminal user no matter what
    program is being run (except see next paragraph).

    Further note: No macros can be called from a terminal that is open in
    image mode, since all input from such a terminal goes uninterpreted to
    the job owning the terminal.  In general, no escape commands can be
    entered from an image mode terminal, for the same reason.

There are two types of macros available: the ESC # CR macro and the
NOEDIT-display macro.  The CHRMAC and GETMAC UUOs have been made to
work for defining and returning definitions for ESC # CR macros as
well as for NOEDIT macros.

      A NOEDIT macro is called by typing the single character that is
      defined as a macro.  Such macros are available only for terminals
      known to the system to be NOEDIT displays.  ("NOEDIT" refers to the
      fact that such terminals have no EDIT key.  Most Datamedias do have
      an EDIT key, which simplifies typing 9-bit characters to the
      system.  For a system-supported display that does NOT have an EDIT
      key, NOEDIT macros are available, again for simplifying typing of
      9-bit characters.)  For more details on definable NOEDIT macros,
      READ NOEDIT.

      An ESC # CR macro is called by typing ESC # CR on a display or
      ↑← # CR on a non-display, where # is a decimal number within the
      allowed range of numbers (currently 5 to 20 inclusive) and CR is
      a carriage return.  Some terminals are or can be programmed to
      transmit the sequence ESC # CR when a single key is depressed.
      In particular, there are 21 such pre-programmed keys on the DM
      3025s with the WAITS keyboard (TTY DMWAITS), including the PF#
      keys at the top of the keyboard.  ESC # CR macros are available
      from any terminal, including PTYs.  (Note: Any ESC # CR command
      where the number # is outside the allowed range for macros, is
      reserved by the system for use in entering special commands.)

Either kind of macro can be defined as an arbitrary string of text
to appear as if typed from the terminal.  The length of any single
macro definition is limited, currently to no more than 18 (decimal)
characters.  Also, the total string length for all macros defined
for a single physical terminal is limited, currently to 192
(decimal) characters.  The string for a definition is represented
in the form in which it would be typed on a Data Disc terminal, and
therefore normally does not include any special multiple character
sequences (used on EDIT and NOEDIT displays to input a single
character).  Among the sequences that will not work inside a macro
are commands of the form ESC " <char> on NOEDIT displays; the
desired function should be programmed into the macro definition
instead.  However, it is permissible and useful to end a macro on a
NOEDIT display with ESC " (leaving the <char> after the quote to be
typed manually) or with one of the NOEDIT commands that causes the
next character to be quoted (with some combination of CONTROL and/or
META bits).  Thus a macro (of either kind) can be used to cause
quoting of the next (manually-typed) character on a NOEDIT display.

Macros are not allowed to call other macros.  By virtue of the
representation used for macros, it is impossible to define a macro
that attempts to call a NOEDIT macro.  It IS possible to define a
macro that ATTEMPTS to call an ESC # CR macro (simply by including
the string ESC # CR in the definition), but such a macro call from
within a macro is a no-op.  It is ignored.

Macro definitions apply to the physical terminal for which they are
defined.  For DD terminals, this means the macro definitions go with
the keyboard, not with any line that the keyboard may be mapped to
at a given moment.  However, this does not prevent the macro
definition from typing text at the currently mapped-to terminal;
that is indeed expected to be a common usage.  However, the
association of macro definitions with the physical terminal means
that mapping commands themselves can be included in macros, as can
audio switch commands, for instance.  Macro definitions can include
essentially anything that you can type from the terminal (except for
macro calling commands).

Macro definitions go away when the terminal for which they are
defined "goes available" (e.g., 15 seconds after logout).  However,
for Data Disc terminals, the ESC # CR macros defined for a DD
keyboard go away only when the last logical line that keyboard is
responsible for goes available.

Macros definitions can include ESCAPE commands (including audio and
video switch commands on Data Discs).  However, ESCAPE commands
executed from inside a macro do not affect the saved ESCAPE command
and argument that are used and/or incremented by the ESCAPE/BREAK
*/+ commands.  Thus, if you type ESC 10 CR followed immediately by
ESC *, then the ESC * will repeat the ESC 10 CR command even if one
or more ESCAPE commands (e.g., ESC 10 U) were executed by the macro.

ESCAPE commands to be included in macro definitions should be in a
form appropriate for the terminal involved.  In particular, ESCAPE
commands on non-displays should use the non-display escape character
↑← rather than the display escape character ESCAPE.

The UUOs used to set up and to find out macro definitions are
described below.  The system program CHRMAC uses these UUOs to
provide general utility functions of defining and reading macros,
including storing and reading definitions from disk files and
copying definitions from other terminals.  The CHRMAC program
documents itself (type R CHRMAC to run it).

- - - - -
      The CHRMAC UUO is used to define a macro.

	MOVEI AC,ADDR
	CHRMAC AC,		;[CALLI 400065]
	 <error return -- code in AC>
	<success return>

ADDR:	MACRO.IDENTIFIER,,LENGTH
	BYTE (12)XX,XX,XX,...	   ;This is the macro's defining string

MACRO.IDENTIFIER specifies which macro is to be defined, that is, what
will be typed to invoke the macro.  MACRO.IDENTIFIER must be either

    (1) 400000 (octal) plus a number (decimal) from 5 to 20 inclusive:
    this form specifies an ESC # CR macro, where # is the number
    specified, from 5 to 20; or

    (2) one of the ascii characters allowed to be defined as a macro on a
    NOEDIT display (the possible characters are all ascii control
    characters -- ↑@ ↑H ↑I ↑J ↑K ↑L ↑[ ↑\ ↑] ↑↑ ↑←): this form specifies a
    NOEDIT macro, which will be invoked by typing the specified character.
    This type of macro can only be defined on a NOEDIT display.  For more
    details on definable NOEDIT macros, READ NOEDIT.

LENGTH is the number of 12.-bit bytes in the macro definition.  If LENGTH is
zero then any previous definition for this macro will be flushed (for NOEDIT
macros this means the character reverts to having its default meaning).  The
current maximum length of a macro is 18 (decimal) characters.

The macro definition itself is made up of a number of 12-bit bytes
starting at ADDR+1.  The bytes are standard 9-bit SAIL characters
(right-justified in the 12-bit bytes), with the following special
12-bit codes allowed also:

    0600    deferred CALL (use two 600s in a row to get CALL, stopping job)
    2000    quote following char (↑Q)    (meaningful only on NOEDIT display)
    2001    quote with CONTROL (↑P)      (meaningful only on NOEDIT display)
    2002    quote with META (↑V)         (meaningful only on NOEDIT display)
    2003    quote with CONTROL-META (↑W) (meaningful only on NOEDIT display)
    4041    BREAK
    4042    ESCAPE
    4044    CLEAR
    4241    HOLD (represented as CONTROL-BREAK)
    4244    UNHOLD (represented as CONTROL-CLEAR)
    4444    FLUSH DISPLAY (DM) QUEUES (represented as META-CLEAR)

If the CHRMAC UUO is successful, it will take the skip return.  If it fails,
then it will take the direct (error) return with an error code in the AC.
The possible error codes are:

    1    NOEDIT macro: job is not on a NOEDIT display
    2    NOEDIT macro: MACRO.IDENTIFIER is not a redefinable character
    3    NOEDIT macro: MACRO.IDENTIFIER is currently the only
	    defined ESCAPE character
    4    LENGTH is greater than maximum allowed (currently 18 (decimal))
    5    Some byte in the definition isn't an allowable SAIL character
    6    ESC # CR macro: number (#) is not in allowable range
    7    Job is detached (no physical terminal to assign definition to)
    10   ESC # CR macro: job's terminal is disowned (no physical
	    terminal is responsible)
    11   Too much macro text in all macros defined for this physical
	    terminal (current max is 192 (decimal) characters)


- - - - -
The GETMAC UUO is used to find out a current macro definition.

	MOVE AC,[<400000+physical terminal number, or zero>,,ADDR]
	GETMAC AC,		;[CALLI 400120]
	 <error return -- invalid terminal specified>
	<success return -- ADDR is set up as CHRMAC arg block>

ADDR:	MACRO.IDENTIFIER,,<length returned here>
	BLOCK 6 	;string of 12.-bit bytes returned here

The left half of the AC specifies the physical terminal whose macro
you want to know.  A zero in the left half of AC specifies the physical
terminal your job is running on (the responsible terminal if the job
is running on a Data Disc terminal).  If the 400000 bit is on in the
left half of AC, then the remainder of the left half specifies the
number of the physical terminal to get the macro from.

The right half of AC points to a block into which the definition is to
be returned, except that the left half (MACRO.IDENTIFIER) of the first
word of that block specifies which macro is to be returned.  The form
of MACRO.IDENTIFIER is exactly the same as that in the CHRMAC UUO
above:  either (1) the ascii character for NOEDIT macro or (2) 400000
plus the number of an ESC # CR macro.  The block is set up in exactly
the form required for a CHRMAC UUO to define that macro.  If the
specified macro is not defined, then the returned length will be zero.

The direct (error) return is taken if either (1) MACRO.IDENTIFIER
specifies a NOEDIT macro and the given terminal is not a NOEDIT display,
or (2) AC specifies that the job's own terminal is to be used and the job
is detached or disowned, or (3) AC specifies an illegal terminal number.

If a valid terminal is specified, then the skip return is taken and the
given macro's definition is returned.  If the MACRO.IDENTIFIER specifies
an illegal or undefined macro, then the returned length will be zero.